home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 7 / Amiga Format AFCD07 (Dec 1996, Issue 91).iso / serious / shareware / comms / internet / html-related / hsc / src_docs / options.hsc < prev    next >
Text File  |  1996-09-30  |  9KB  |  217 lines
  1. <WEBPAGE chapter="hsc - " title="Invoking hsc"
  2.     PREV="install.html"
  3.     NEXT="examples.html"
  4.     QTEXT=("shoulder, bicep, elbow, arm<BR>"
  5.           +"forearm, thumb, wrist, knuckle, palm<BR>"
  6.           +"middle, pinky, index, ring<BR>"
  7.           +"dinner bell dinner bell ding")
  8.     QAUTHOR='They Might Be Giants, "Dinner Bell"'>
  9.  
  10. <*
  11. ** macro to format an explanation
  12. *>
  13. <$MACRO explan TITLE:string/r NAME:string ONLYDEFTAG:bool>
  14. <** create named reference **>
  15. <$IF COND=(SET NAME)>
  16. <A NAME=(Name)><$ELSE>
  17. <A NAME=(Title)></$IF>
  18. <DT><** create heading **>
  19. <KBD><(title)></KBD></A>
  20. <$IF COND=(ONLYDEFTAG)>
  21. (for use within <ln_deftag> only)
  22. </$IF>
  23. <DD>
  24. </$MACRO>
  25.  
  26. <*
  27. ** macro to format example for IGNORE
  28. *>
  29. <$MACRO exmp_ign VALUE:string/r>
  30. <DT><KBD><(value)></KBD>
  31. <DD>
  32. </$MACRO>
  33.  
  34. <H2>General rules</H2>
  35.  
  36. <P>As <hsc> is an tool developed under AmigaOS and I never liked
  37. the cryptic "cmd -cvf -osepp.x"-way of invoking commands comming
  38. from Unix, <hsc> uses a syntax like most commands of AmigaOS;
  39. even for ports on other operating-systems.</P>
  40.  
  41. <P>All options and swiches are case-insensitive. If you start <hsc>
  42. without any options, a short help message will be displayed.</P>
  43.  
  44. <P>Options require an additional argument, for example a file.
  45. All of the below terms are treated as the same: 
  46. <KBD>FILE hugo.hsc</KBD>, <KBD>file hugo.hsc</KBD> or 
  47. <KBD>file=hugo.hsc</KBD>.
  48.  
  49. <P>Switches are enabled if their keyword is detected within
  50. the command-line.</P>
  51.  
  52. <P>If you still don't understand this, get a manual for AmigaOS.</P>
  53.  
  54. <H2>Options</H2>
  55.  
  56. <DL>
  57. <EXPLAN TITLE="HELP" NAME="help">
  58.     Display a short help message and exit.
  59. <EXPLAN TITLE="LICENSE" NAME="license">
  60.     Display a short version of the <A HREF="../COPYING">GNU General
  61.     Public License</A> and exit.
  62. <EXPLAN TITLE="[FROM=]<I>inputfile-name</I>" NAME="from">
  63.     Specifies the input filename. To use <stdin> as
  64.     input file, the peudo-filename <CODE>STDIN</CODE> (case sensitive)
  65.     should be specified. If you specify more than one file,
  66.     the last file is taken as mainfile, and all previous files are
  67.     included before it. This is useful to include macro-definitions
  68.     within the command-line instead of an <ln_include> in the hsc-source.
  69. <EXPLAN TITLE="TO=<I>output-filename|destination-directory</I>" NAME="to">
  70.     Specifies the output filename or the destination directory.
  71.     If the argument ends with a "<KBD>/</KBD>" (or also "<KBD>:</KBD>"),
  72.     it is interpreted as a directory. In this case, the name of the
  73.     outputfile is created from the name of the input file, with an
  74.     extension specified (see below).<BR>
  75.     If no output file is set, <stdout> is used instead.
  76. <EXPLAN TITLE="EXTENSION=<I>output-extension</I>" NAME="extension">
  77.     If you specify a directory for output, the output-filename
  78.     will depend on the input-filename and the extension specified
  79.     with this options. If you do not set an extension, "<CODE>html</CODE>"
  80.     will be used. A period (`<CODE>.</CODE>') will be added automatically.
  81.     Setting <KBD>EXTENSION=.</KBD> will ommit this and result into exactly 
  82.     the same filename as the input.
  83.     If you specify a complete filename for output, this option has no
  84.     effect.
  85. <EXPLAN TITLE="MSGFILE=<I>message-filename</I>" NAME="msgfile">
  86.     Redirects messages to a file. By default, <stderr> ist used.
  87. <EXPLAN TITLE="MSGFORMAT=<I>format-description</I>" NAME="msgformat">
  88.     Describes how messages should be displayed. Legal placeholders:
  89.     <PRE>
  90.         %f      filename
  91.         %x, %y  location in file (column, line)
  92.         %c      message class
  93.         %i      message id (numeric)
  94.         %m      message text
  95.         %n      inserts a linefeed
  96.     </PRE>
  97.     Example: To get GCC-like messages, use
  98.     <CODE>MSGFORMAT="%f:%y: %c %i: %m"</CODE>.
  99. <EXPLAN TITLE="PREFSFILE=<I>preferences-filename</I>" NAME="prefsfile">
  100.     Specifies filename for <A HREF=":features/prefs.html">sytax-definition</A>
  101.     to be used, if you don't want to use the defaults.
  102.  
  103. <EXPLAN TITLE="PRJFILE=<I>project-filename</I>" NAME="prjfile">
  104.     Stores some information about the document currently processing
  105.     in a seperate file to extend functionality. Read the section
  106.     about <A HREF="project/index.html">Project managment</A> for more
  107.     details. Note that all documents within a project should use the
  108.     same project-file.
  109.  
  110. <EXPLAN TITLE="DEFINE" NAME="define">
  111.     Defines a global attribute. The syntax is equal to <ln_define>, exept
  112.     that you need no quotes surrounding the value.<BR>
  113.     Example: <CODE>DEFINE "hugo:string=hugo was here"</CODE>
  114.  
  115. <EXPLAN TITLE="IGNORE" NAME="ignore">
  116.     Ignore warning message number. Usually, <KBD>IGNORE</KBD> needs a numeric
  117.     argument and can occure multiple. Example:
  118. <PRE>
  119.         IGNORE=21 IGN=18 IGN 3         (ignore warnings #21, #18, #3)
  120. </PRE>
  121.     Additionally, you can give <KBD>IGNORE</KBD> some special values:
  122.     <DL>
  123.     <EXMP_IGN VALUE="ALL">
  124.         Ignore all non-error messages
  125.     <EXMP_IGN VALUE="NOTES">
  126.         Ignore all notes
  127.     <EXMP_IGN VALUE="BADSTYLE">
  128.         Ignore all bad style warnings
  129.     </DL>
  130.     All these special values add new messages to the list of messages
  131.     to be ignored, but do not reset any <KBD>IGNORE</KBD>s passed before.
  132. <EXPLAN TITLE="MODE" NAME="mode">
  133.     Set base mode for syntax check. Legal values are <KBD>PEDANTIC,
  134.     NORMAL</KBD> and <KBD>RELAXED</KBD>. Default is <KBD>NORMAL</KBD>.
  135.     This only disables several messages and warnings from the beginning.
  136.     Any <KBD>IGNORE</KBD>s passed before are reseted.
  137.  
  138. <EXPLAN TITLE="QUOTESTYLE" NAME="quotestyle">
  139.     Specifies which kind of quotes should be used to surround 
  140.     attribute-values. <KBD>KEEP</KBD> keeps the user-kind, 
  141.     <KBD>DOUBLE</KBD> tries to assign double quotes 
  142.     (eg. <CODE>"value"</CODE>), 
  143.     <KBD>SINGLE</KBD> tries to assign single quotes 
  144.     (eg. <CODE>'value'</CODE>) and <KBD>NONE</KBD> will remove
  145.     quotes if possible.
  146.  
  147. <EXPLAN TITLE="STATUS" NAME="status">
  148.     Display several status messages (output goes to stderr). Legal
  149.     flags are:
  150.     <UL COMPACT>
  151.     <LI><KBD>QUIET</KBD>: no status messages
  152.     <LI><KBD>LINE</KBD>: display name and line of file currently processing
  153.         Included files are also displayed. After processing a file,
  154.         the filename and the total number of lines remain visible.
  155.     <LI><KBD>VERSION</KBD>: display program title and version
  156.     <LI><KBD>VERBOSE</KBD>: enable verbose status messages; this includes
  157.         the information displayed during the  processing of <ln_exec>
  158.         and some details about images, if <op_getsize> has also been
  159.         enabled.
  160.     <LI><KBD>FULL</KBD>: enable all status messages
  161.     </UL>
  162.     The above flags can be combined by separating them with a <vbar>,
  163.     eg <KBD>STATUS=line|version</KBD>, exept for <KBD>QUIET</KBD>
  164.     and <KBD>FULL</KBD>
  165. <EXPLAN TITLE="STRIPTAGS=<I>tag-list</I>" NAME="striptags">
  166.     Strip some specific tags from document. <I>tag-list</I> is a string,
  167.     that contains all tags that should be stripped, sepparated by a
  168.     <vbar>.<BR>
  169.     See also <op_stripcomment> and <op_stripexternal>.
  170. <EXPLAN TITLE="ICONBASE=<I>base-uri</I>" NAME="iconbase">
  171.     Replace all icon-entities by images that must be available in
  172.     <I>base-uri</I>. For
  173.     example, with <KBD>ICONBASE=:icons</KBD>, the entity
  174.     <CODE>&back;</CODE>
  175.     is replaced by <TG>IMG SRC=":icons/back.gif" ALT="back"</TG>. Note
  176.     that this argument does not denote a directory, but an URI. It's
  177.     recommended to use an <fe_absuri>. If you don't want to use 
  178.     <KBD>*.gif</KBD>-files for your icon-entities, you can use an asterisk
  179.     (`<KBD>*'</KBD>) to be replaced by the name of the icon-entity;
  180.    eg. <KBD>ICONBASE=:icons/*.png</KBD>.
  181. </DL>
  182.  
  183. <H2>Switches</H2>
  184. <DL>
  185. <EXPLAN TITLE="COMPACT" NAME="compact">
  186.     <A HREF="features/strip.html">Strip redundant linefeeds
  187.     and white-spaces</A> from output.
  188. <EXPLAN TITLE="-DEBUG" NAME="-debug">
  189.     If you've compiled <hsc> in debug-mode, it will send lots of
  190.     information to <stderr>. Otherwise, this option is
  191.     equivalent to <KBD>STATUS=FULL</KBD>.
  192. <EXPLAN TITLE="GETSIZE" NAME="getsize">
  193.     <A HREF="features/getsize.html">Get width and height of images</A>
  194.      and set corresponding attributes
  195.     <CODE>WIDTH</CODE> and <CODE>HEIGHT</CODE> with these values;
  196. <EXPLAN TITLE="MSGANSI" NAME="msgansi">
  197.     Uses ansi-sequences to make messages more readable.
  198. <EXPLAN TITLE="RPLCENT" NAME="rplcent">
  199.     <A HREF="features/rplcent.html">Replace special characters</A> with
  200.     its entity (eg `<CODE>ü</CODE>' becomes `<CODE>&uuml</CODE>').
  201. <EXPLAN TITLE="RPLCQUOTE" NAME="rplcquote">
  202.     Replace double-quotes (`<CODE>"</CODE>') found in the text by 
  203.     <CODE>&quot;</CODE>. This does not affect quotes used inside
  204.     attribute-values.
  205. <EXPLAN TITLE="SMARTENT" NAME="smartent">
  206.     Replace special characters `<CODE>&</CODE>", `<CODE><</CODE>'
  207.     and `<CODE>></CODE>' with their entities
  208.     (<CODE>&amp;, &lt;</CODE> and <CODE>&gt;</CODE>) if they are
  209.     surrounded by white-spaces. 
  210. <EXPLAN TITLE="STRIPCOMMENT" NAME="stripcomment">
  211.     Strip all SGML-comments from input.
  212. <EXPLAN TITLE="STRIPEXTERNAL" NAME="stripexternal">
  213.     Strip tags which refer to an external URI.
  214. </DL>
  215.  
  216. </WEBPAGE>
  217.